FONT CHARACTER SPACING

Each character of a font has a pixel width associated with it. When the 
character is displayed the text cursor advances by that width. The font also 
has a line spacing value associated with it. The line spacing value 
determines how many pixels are to occur between text lines (vertical 
spacing). 


FONT CHARACTER DISPLAY

In font display mode characters have transparent backgrounds. That is, only 
pixels that are on are written to the screen. So a character cell around the 
character is not cleared. The XOR writing mode can be set via the TYPE SCREEN 
statement to cause characters to be blended with the current display. If XOR 
writing mode is off then characters are painted over the display.  

Because of the way in which characters are displayed, it is possible to 
overtype characters in a manner similar to on a typewriter producing the 
combined effect of more than one character.  

To remove a character from the screen, position the cursor to the exact 
location of the character, set the XOR writing mode (TS:O1) then type the 
same character again.  

See also: NH:, Font Editor

NEW KEY - define keyboard codes


       NX: x,y ; x,y . . .
       NXS:

The NX: statement may be used to change the code generated by any key on the 
keyboard. The normal codes generated are shown in appendix B. The number x 
shown above stands for the normal default value of a key, the letter y stands 
for the new value to be generated by the key. Both numbers are always in the 
range 0 to 255. Any number of keys may be redefined in one NX: statement. 
Each x,y pair is separated from the next by a semi-colon.  

Once a key has been redefined it affects all ACCEPT statements except those 
with the X modifier. The X modifier on an ACCEPT statement causes any key re-
definitions to be ignored for that ACCEPT.  

The NXS: statement causes all keyboard keys to revert to their default 
values. NXS: undoes the effect of all previous NX: statements.  

EXAMPLE 1: new keys

       R: cause key f1 to generate code 225 (Beta)
       NX: 187,225

       R: cause upper case A to give a-accent
       NX: 65,160
       . . .
       R: restore upper case A to normal
       NX: 65,65

See also:  ACCEPT
    
PROBLEM - set options


       PR: option-list
       P:  option-list
       PS: list

PROBLEM has two uses.  The first is to provide a destination point for a J:@P 
statement.  In this case PROBLEM can be put at the very end of each frame or 
question.  The option list would usually be omitted in this case. If the 
option list is omitted, then all options retain the settings prior to the 
PROBLEM statement.  

The second use is to specify one or more lesson options.  Lesson options 
control various aspects of student responses, such as automatic case 
conversion of student answers or the student response time limit. Each option 
can be set (turned on) or it can be reset (turned off).  

The option-list consists of one or more of the option letters below.  If the 
S modifier is not appended to the op code, then all options not included in 
the option-list are cleared or turned off.  If the S modifier is appended to 
the op code (PS:), then options previously set remain set.  Each option is 
then set if the corresponding letter is present in the option list. The 
possible options are shown here.  

U  -  if set, all student responses translated to upper case 

L  -  if set, all student responses translated to lower case 

S  -  if set, all spaces are removed from student responses 

G  -  if set, the GOTO command is enabled

E  -  if set, the ESCAPE command is enabled

F  -  if set, the function key ESCAPE command is enabled 

I  -   if set,  error messages suppressed

Error messages are not displayed, but the E flag is still set. 

Kname  -  set KEEP file name

Sets the file name used by subsequent KEEP statements to name. name can be 
any file or path name per DOS conventions.   

W  -  clear label table

Clears the label table and forgets about all labels passed so far.  Thus it 
is impossible to jump backward.  This allows re-use of the same labels. (Not 
recommended for use, present for compatibility only.) 

An  -  set answer maximum length

Sets maximum ACCEPT response length to n characters. n may be a number from 1 
to 256.  A value of n less than 1 or greater than 256 sets the maximum 
response length to 256.  

Z  -  causes U, L, S, G, P and E options to be turned off  

Tn  -  set answer time maximum

Set max Accept response time to n seconds, where 1<n<32767. T0 sets back to 
no limit.  

P -  turn on printer echo

Turn "printer-echo" on. Once on then all characters typed to the display are 
also sent to the system printer. It is up to the user to insure that the 
printer is on and ready since the program can be delayed if it is not ready. 
Use the Z option above to turn "printer-echo" off.  

Note:  The "R" of "PR:" may be omitted.  It is allowed for COMMON PILOT 
compatibility.  

EXAMPLE 1: Problem statements 

       P: T10
                             - response limit=10 sec
       P: U S
                             - upper case, spaces removed
       P: F 
                             - enable FUNCTION key escape
       PS:G
                             - set GOTO, leave others as before
       P:P
                             - turn printer-echo on

See also:  ACCEPT, KEEP, GOTO AND ESCAPE         
 
POKE,OUT - set memory or do output 


       PX:offset,value
       PJ:address,value

These statements are not normally used. They are provided for the programmer 
who has need to program directly at the hardware level.  

The value must be a number or expression from  0 to 255. PX: stores the byte 
value in memory at the offset given. The offset is from a segment whose base 
is specified by the system variable %A. Great care must be taken in using 
this statement as a mistake can cause system failure.  

PJ: Performs a machine level OUT instruction to the device address given of 
the byte value.  

EXAMPLES: 

If you have both types of video adapters (monochrome and color) you can 
switch from the monochrome to the color for PILOT output via ...  

       C: %A=0
       PX: 1040,pek(1040)-16
       (then set desired mode via TS: statement)

and you can change back to the monochrome via...  

       C: %A=0
       PX: 1040,pek(1040)+16
       (then set desired mode via TS: statement)

Note: the above example is given for illustration purposes only. The TS: 
statement provides a simple way to change video adapters.  

REMARK - program comment

       R: remarks

REMARK is ignored during program execution.  It can be used to document a 
PC/PILOT program.  

EXAMPLE:   

       R: This section displays the main menu.


SOUND - generate tones

       S: list

SOUND is used to generate simple tones, noises or beeps for audio feedback.  
The list contains one or more pitch or pitch,duration values.  The entries in 
the list are separated by the ";" character.  The two possible forms of a 
list entry are: 

       pitch
       pitch, duration

where pitch is a number or variable from 0 to 2047 and duration is a number 
or variable from 1 to 63.  A duration of 34 gives about a one second tone. 
The lower the pitch value the higher the tone.  The higher the duration 
value, the longer the tone is played.  If the duration is omitted after a 
pitch (first form above) then the duration of the previous pitch is used. A 
pitch or duration value can be an integer number, a variable name, or an 
expression enclosed in parentheses.  

It is possible to repeat a series of notes by the notation: 

       *n(list)

where n is a number or a variable. A pitch value of 0 give silence. Normally, 
doubling a pitch lowers it by one octave. Halving a pitch raises it by one 
octave.  

EXAMPLES:

       S: 200,25;300,8;100,18   
       S: *4(208,5;224)
       R: next two lines play a two-octave scale
       S: 500,10;446;400;374;333;301;266;250
       S: 250,10;223;200;187;166;150;133;125

TYPE - display text on screen


       T: text
       TH: text
       TX: text
       : text

The TYPE statement is used to display text on the screen. TYPE might be used 
to provide narrative, instructions, questions, feedback or computational 
results. The data you place after the colon is displayed on the screen.  

EXAMPLE 1: simple TYPE statement

       T:We will now discuss stock options.

The text is always displayed within the currently defined viewport. Any 
display data outside the current viewport is unaffected by the TYPE. The use 
of a viewport is explained under the TYPE SCREEN statement. The text is 
placed at the current cursor location, advancing the cursor, automatically 
wrapping to the start of a new line if necessary.  Unless otherwise 
specified, the cursor is returned to the start of the next line within the 
viewport. If necessary, the viewport is scrolled up one line to accommodate 
the text.  


TYPE HANG, SUPPRESS NEW LINE

Appending the H, or hang, modifier to the TYPE, TH:, suppresses the automatic 
return to the next line at the end of the text. Instead, the cursor is left 
at the position immediately after the last displayed text character.  


CURSOR POSITIONING

You can use the TS:, or TYPE SCREEN statement to move the cursor to any 
desired screen location.  


CLEARING THE SCREEN 

Appending the X, or clear, modifier to the TYPE, TX:, clears the viewport and 
moves the cursor to home position prior to the text display. Home position is 
the upper left corner of the viewport.  


CONTINUATION OF A TYPE

A TYPE statement may be continued on the next line by starting the next line 
with a colon. You may continue a TYPE in this manner for any number of lines.  

EXAMPLE 2: continuation of a TYPE

       T:Point D is the
       :
       :   A  mean
       :   B  median
       :   C  mode


TYPING A $ OR A # CHARACTER

Since PILOT uses the $ and the # as special characters within a TYPE, to 
actually display one of these characters, place two adjacent $ or # 
characters in the text. For example 

       T:You owe $$5.00.

would actually display  "You owe $5.00." 


TYPING VARIABLES OR EXPRESSIONS

You can type the value of a variable or an expression within the text. To 
type the value of a variable precede the variable name by a "$" or a "#", and 
follow the variable name by a space.  The value of the variable will be 
displayed at the corresponding place. The name of the variable and the space 
after the variable name are not displayed.  

EXAMPLE 3: variables in a TYPE

       T:You got #X  right.
       might display    You got 37 right.

       T:This is an example of $ABC$  learning.
       might display  
       This is an example of cognitive learning.

In the first example, X is a numeric variable, whose value, 37, is 
substituted in the displayed text. In the second example, ABC$ is a string 
variable whose value, "cognitive", is substituted in the displayed text. Do 
not be confused by the notation, $ABC$. The first $ indicates that a variable 
is included in the text of a TYPE statement. The second $ is actually part of 
the string variable name ABC$, since all string variable names end with a $.  

Programming note: By PILOT language convention, the $ is usually used to 
precede a string variable and the # is used to precede a numeric variable. In 
fact, this implementation of PILOT allows you to use either symbol for either 
type of variable.  

The text may contain an expression preceded by a # or $ and enclosed in 
parentheses.  The value of the expression is displayed in the text.  

EXAMPLE 4: expression within TYPE

       T:The total is #(A+B+C) .
       might display    The total is 102.
    

TEXT AND BACKGROUND COLORS

The current text and background colors can be changed within the text of a 
TYPE. To set the text color put a # followed by a number. To set the 
background color put a $ followed by a number. This facilitates the use of 
color to highlight a word or phrase within a sentence. The number may be one 
or two digits only.  

EXAMPLE 5: changing colors

       T:The #2 civil #3 war ended in $011865.

The word "the" is displayed in whatever the text color was prior to this 
statement. The word "civil" is displayed in color 2, the word "war" is 
displayed in color number 3. Note that 1865 is printed in background color 1. 
Only the 01 makes up the background color number since it is two digits.  


EXTENDED AND USER-DEFINED

CHARACTERS

All characters, from character code 32 to 255 can be displayed. Codes from 0 
to 31 not reserved for control characters may also be displayed via a command 
such as  T:$(CHR(25)).  Codes from 32 to 127 are the standard ASCII 
characters. Character values from 128 to 255 are used in text modes for the 
extended character set built into the computer. In graphics modes, codes 128 
through 255 are available for user-defined characters.  


CHARACTER FONTS

The NS: statement can be used to change to a character font for all text 
output. Character fonts can be used to display characters of all sizes and 
styles. See the NS: statement for more information on the use of character 
fonts. 


XOR TYPE MODE

In graphics modes 4, 5 and 6 the text can be displayed in one of two ways. 
The normal way is to display the character in the character cell such that it 
writes over the previous display data in the cell.  The second way is called 
XOR mode. XOR causes the text to be combined with any display data that may 
already be in the character cell on the screen. This is accomplished by a 
logical exclusive or of the character pattern with the display screen. The 
effect is to not obscure previous graphics data that may have been in the 
character cell. Thus it would be possible to have a line or other graphic 
element pass right through a character.  The TYPE SCREEN statement is used to 
select the character writing mode.  


CONTROL CHARACTERS

These cursor control characters may also be output by placing within an 
expression or string variable.  

       CHR(8) =BACKSPACE
       CHR(9) =FORWARD SPACE
       CHR(10)=DOWN
       CHR(11)=UP
       CHR(12)=CLEAR
       CHR(13)=NEWLINE
       CHR(14)=HOME

DOWN and NEWLINE scroll the viewport up if the cursor is on the bottom line.  
UP scrolls the viewport down if the cursor is on the top line.  


See also:  TYPE SCREEN, NEW CHARACTER
 
TYPE SCREEN - set screen options


       TS: command-list

TYPE SCREEN is used to control screen modes and colors, define viewports on 
the screen, set line spacing and create animated character graphics.  

The command-list consists of one or more of the following commands.  Each 
command is separated from the next by a ";" character.  In the command 
descriptions below lower case letters denote a numeric variable, integer 
constant, or an expression enclosed in parentheses.  

Mn - set mode

Set screen mode and erase screen. Screen modes are 0 through 6. On the IBM 
EGA modes 13, 14 and 16 are also supported.  

MnC - set mode and select color adapter

Placing C after the number switches to the color adapter card.  

MnM - set mode and select monochrome adapter

Placing an M after the number switches to the monochrome adapter card. These 
two options are only used if you have both types of display adapters and wish 
to switch back and forth.  

Ln - set line spacing

Set spacing between text lines, n<=1 sets single spacing,  n=2 sets double 
spacing, etc..  

Fn - set foreground color

Set foreground text color, possible values shown below.  

Fn,a - set color palette register

Supported only on EGA. Sets a color in the logical color palette register for 
color number n.  Logical color n is set to actual color a. All display data 
currently displayed in color n changes immediately to color a.  

Bn - set background color

Set background color, possible values shown below.  

En - erase to background color

Set background color and clear the current  viewport to the background color; 
cursor set to home position in viewport.  

Rs,c,r - draw a rectangle outline

A rectangle is drawn with the upper left corner at the current cursor 
location. The rectangle is c character cells wide and r character rows deep. 

In text mode, if the value for s is 1 or 2 then the rectangle is drawn with 
the special line drawing characters of the extended character set, using the 
appropriate horizontal, vertical and corner line characters. A value of 1 
indicates single line characters, a value of 2 indicates double line 
characters. A value of s=0 in text mode indicates that only blanks are 
written. This implies that by setting the background color to the desired box 
color a box of the background color is drawn.  

In graphics mode the value of s=0 indicates that the "*" character is to be 
used to draw the box. A value of 1 or two indicates the use of the same 
characters used in text mode to draw single and double line rectangles. But 
since these characters are in the user-defined range, the actual border 
character patterns used are as defined by the program. 

On - set overlay mode to xor or normal

Sets the graphics and text overlay mode to normal for n=0, or to XOR mode for 
n=1.  Cn - control cursor 

Controls the cursor appearance. If n is zero, the cursor is invisible. If 
using a text mode, then n=1 gives the normal underscore cursor, and n=2 gives 
a block cursor. If using graphics mode, then n is the character number, from 
1 to 255 to be used as the cursor. The normal cursor is n=95, the underscore 
character.  
           
Xn - set border color

In modes 0-3 sets color of the border or  outer  frame of  the  screen,  in 
modes  4 and 5 has same effect as Bn,  in mode 6 sets the text color.  

Vl,r,t,b - select viewport

Set screen viewport to be from column l on the left through column r on the 
right  and  from  row t  on  the  top through  row b on  the  bottom.   See 
below for more information.  

V; - restore previous viewport

Restores the previous viewport and cursor position.  

Atext - animate text block

Animate: the text is displayed from the cursor position. If the text contains 
a "/" character, the "/" is not displayed but the next character is displayed 
on the next line down and directly under the original cursor location. Text 
is displayed up to a ";" or to the end of the statement.  After the text is 
displayed the cursor is left where it was when the animate began. This 
command is useful to draw figures made up of a block of several redefined 
characters.  

A$var$ - animate a string variable

Animate as described above using the contents of the string variable as the 
text.  

Pn - select display page

Display text page n. In modes 0 and 1 n may be 0-7, in modes 2 and 3 n may be 
0-3, in modes 4-6 n may be 0 only. In the text modes (0-3) there are multiple 
display pages, one of which is the currently visible page on the screen. The 
normal default is PO.  

Pn,w - select display and writing page

Displays text page n but makes text page w the current page to be written on 
by TYPE statements. Thus the student can view one page while the program 
prepares another page for display. The TEXTWIPE utility (AFL) may be useful 
in manipulating text pages.  

Dn - delay

Delay for n 60ths of a second. This is useful when using animate within a 
loop to move a figure on the screen.  

Wrlud - walk cursor

Walk right, left, up or down. The W can be followed by any number of r, l, u, 
or d characters. Each one moves the cursor one space in the indicated 
direction.  Moving down on the bottom line of a viewport causes the viewport 
to scroll up; moving up on the top line causes the viewport to scroll down.  

Gx,y - goto column, row

Position the cursor in column x and row y of the current viewport. G0,0 goes 
to the home position of the viewport.  

*n(... ) - loop

Repeats the commands in parentheses n times. Any of the above commands may be 
in the parentheses. This is useful to move a figure by repeating a sequence 
of animate, delay and walk.  
 

VIEWPORTS

A viewport is a section of the screen which is used to display all text 
output by the program.  When PILOT starts the current viewport is defined to 
be the entire screen (V0,39,0,24).  The Vl,r,t,b command defines a new 
section of the screen to be the current viewport.  When this is done the 
cursor is placed in the home position of the viewport.  All text displayed by 
the program is displayed only in the current viewport, any data displayed 
outside the viewport is unaffected as the viewport changes, clears, scrolls, 
etc..  

A V command without the four numbers puts the viewport and cursor back to the 
position prior to the last V command.  This simplifies alternating between 
two viewports on the screen, and is useful for student responses and program 
feedback.  Viewports are also useful to retain instructions, questions or 
graphs outside a viewport while conversation takes place within the viewport.  

EXAMPLE 1: Establishing a viewport from column 5 through 
column 30, and from row 18 through row 25, inclusive.  

       TS:V5,30,18,25


SCREEN MODES

There are several possible screen modes. Each mode allows different screen 
characteristics.  Modes 0 through 3 are called TEXT modes since only text, 
not graphics, can be displayed in these modes. Modes with numbers 4 or higher 
are called GRAPHICS modes since both text and graphics can be displayed.  


TEXT MODES

In the text modes there are either 40 or 80 columns across.  There are always 
25 lines of text.  Each character cell has a unique background color, and a 
foreground or text color. Characters from the standard ASCII and extended 
character set can be displayed. There are 16 possible colors available.  

GRAPHICS MODES 

In the graphics modes there may be 40 columns or 80 columns, and 25 lines of 
text. The text may consist of the standard ASCII characters or the 128 user-
definable characters.  The background color is a screen-wide attribute, that 
is, when the background color is selected, the entire screen background 
changes immediately. In these modes, the GRAPHICS statement may be used to 
draw turtle graphics or display full screen graphics images. There are two 
possible 4-color sets, each with two possible intensities. 

  
THE 16 AVAILABLE COLORS

There are 16 standard colors available. Some modes permit the display of all 
16 at once, others permit display of a subset of the colors. These color 
numbers run from 0 to 15. The colors from 8 through 15 are brighter versions 
of the same colors in the range 0 through 7. 

          0 - black
          1 - blue
          2 - green
          3 - cyan
          4 - red
          5 - magenta
          6 - brown
          7 - grey

Color 14 (brighter brown) is yellow. Color 15 (brighter grey) 
is white.
 

MODES 0 AND 1

Text modes, 40 columns, 25 lines, text colors 0-15, background colors 0-7, 
adding 8 to background causes blinking, no graphics, available on all 
graphics adapters. Each character cell on the screen has its own background 
and foreground attribute. When a character is written to the display the 
character cell takes on the attribute according to the current foreground and 
background settings. 


MODES 2 AND 3

Text modes, 80 columns, 25 lines, text colors 0-15, background colors 0-7, 
adding 8 to background causes blinking, no graphics, available on all 
graphics and monochrome adapters. Each character cell on the screen has its 
own color attributes as described above for modes 0 and 1. 


MODES 4 AND 5

Graphics modes, 40 column text, 25 text lines, 320 pixels across, 200 pixels 
down, text and graphics colors 1,2 and 3. Background color is color 0. It may 
be set to a value from 0 to 16. Adding 16 to the background color number 
gives a higher intensity off all the colors on the screen. When the 
background changes, the entire screen's background changes immediately. Text 
may be displayed via the hardware character set, user-defined characters or 
character fonts. All types of graphics available.  


COLORS IN MODE 4

          0 - current background color
          1 - GREEN
          2 - RED
          3 - YELLOW

Note: lower intensity YELLOW becomes BROWN. 


COLORS IN MODE 5

          0 - current background color
          1 - CYAN
          2 - MAGENTA
          3 - WHITE


MODE 6

Graphics mode, 80 column text, 25 text lines, 640 pixels across, 200 pixels 
down, background color is 0 (black), foreground color is 1, normally white, 
can be set via TS:Xn command. Text may be displayed via hardware character 
set, user-defined characters or character fonts. All types of graphics 
available. 


EXTENDED GRAPHICS ADAPTER

When using the IBM EGA there are several additional functions which can be 
utilized. The EGA provides higher resolution, more colors and 80 column text 
with 16 color graphics. The EGA also permits the modification of the colors 
assigned to the 16 standard color numbers via control of the color palette. 
In the EGA modes image graphics, sprites and user-defined characters are not 
supported.  Character fonts are supported. Three additional screen modes are 
supported. Selection of one of the EGA modes on a non-EGA system can give 
unpredictable results.  The EGA supports modes 0 through 6 as described 
above.  


MODE 13

Graphics mode, 40 column by 25 line text. Graphics is 320 across by 200 down. 
Colors are 0-15 for text and graphics. Text may be displayed via hardware 
character set or character fonts. Turtle graphics can be used.  Image and 
sprite graphics can not be used.  


MODE 14

Graphics mode, 80 column by 25 line text. Graphics is 640 across by 200 down. 
Colors are 0-15 for text and graphics. Text may be displayed via hardware 
character set or character fonts. Turtle graphics can be used.  Image and 
sprite graphics can not be used.  


MODE 16

Graphics mode, 80 column by 25 line text. Graphics is 640 across by 350 down. 
Colors are 0-15 for text and graphics.  Text may be displayed via hardware 
character set or character fonts. Turtle graphics can be used.  Image and 
sprite graphics can not be used.  


EGA COLOR PALETTE

The EGA has logical color registers, or a color palette, as it is called. 
There are 16 logical color registers which correspond to the sixteen logical 
colors 0-15. Each register may contain an actual color number from 0 to 63 
which tells what visible color is displayed for the logical color. The color 
registers are active in all screen modes and can be set via the TS:Fn,a 
command shown above. Changing the actual color for a logical color in which 
data is currently displayed causes the display to change immediately. This 
can be used to your advantage to create dynamic displays.  


NORMAL AND XOR WRITING MODES

In graphics modes 4, 5 and 6 the text and turtle graphics can be displayed in 
one of two ways.  The normal way is for text characters to replace the entire 
character cell with the character and graphics output to replace each pixel. 
An alternate way can be selected via the TS:O1 command shown above. XOR mode 
causes a character or graphic element to be combined with the current display 
data via a logical exclusive or operation. Using this mode a text character 
can be placed over a graphic display without obscuring an entire 8 by 8 pixel 
character cell.  Two characters can also be displayed in one character cell, 
giving the effect of an overstrike capability. Two lines can intersect, 
showing the point of intersection in the combined colors.  


CHARACTER ANIMATION

The TS: statement can be used to construct animated 
sequences by moving blocks of characters on the screen. 
For more sophisticated animation it is recommended that 
you use sprite animation, explained in the SPRITES section 
of this document.  

This example shows how to move a figure across the screen left to right then 
right to left. The figure is a 4 letter block: 

       WX
       YZ

However, it could be any user defined characters as well.  Notice that the 
animation string is carefully laid out with spaces to insure that each redraw 
of the figure completely overtypes the previous one so a trail is not left 
behind.  The number after the D controls the speed of motion.  

EXAMPLE 2: animate a block of characters

       TS:M1;B0;F1;*20(A WX/ YZ;WR;D5)
       TS:*20(WL;AWX /YZ ;D5)

MONOCHROME ADAPTER CARD
 
The various modes and colors apply only to the color adapter card.  On a 
monochrome adapter the screen always works in 25 by 80 mode. It is 
recommended that you use only mode 2 if your program is to run on a 
monochrome adapter.  

See also:  TYPE, GRAPHICS
                       
USE - call a subroutine


       U: destination

The USE statement is used to call a subroutine.  

USE jumps to the destination and saves the location of the statement after 
the USE on the use-stack.  A subsequent END statement in the subroutine 
causes a return to the statement after the USE.  

The destination can be any of those described for JUMP, though the only one 
which normally makes sense is a statement label.  

USE statements can be nested. That is, a subroutine can call another 
subroutine with another USE statement. The maximum nesting level is 32 levels 
deep.  

USE is similar to gosub in basic.  

EXAMPLE: a subroutine call

       T:Typed first
       U:GLOSS
       T:Typed fourth
       E:
       . . .
       *GLOSS
       T:Typed second
       T:Typed third
       E:

EXAMPLE 2: String variable contains the name of             the subroutine to 
call. 

       X:"U:" !! X$

See also;  END, JUMP
                         
VIDEO - call external driver program


       V: variable$

VIDEO is intended to allow a PILOT program to call a machine language 
subroutine. It was originally used to call interface routines for video disc 
and tape players. However, it could be used for many other purposes, since it 
is actually a general purpose interface to any machine language program. (In 
fact, most video devices do not need this type of driver program and can be 
controlled directly by output from the FILE OUT statement.) 

The only argument of a VIDEO statement is the name of a string variable.  The 
string variable must have been dimensioned long enough to contain the machine 
language subroutine and the subroutine must have been placed into the string. 
The DX: op code must be used to dimension the string variable. This insures 
that the string begins on a 16-byte boundary.  

The VIDEO statement causes the machine language FAR CALL to be executed to 
the first byte of the string. Upon entry to the subroutine the code segment 
and data segment registers are equal and point to a segment which contains 
the subroutine at offset zero.  Segment registers must not be modified upon 
return from the subroutine. Other registers may be used without saving the 
contents. The subroutine must return via a FAR RETURN op-code. Data can be 
passed to/from the subroutine by the PILOT program in mutually decided 
portions of the string variable itself.  The PILOT program can use 
subscripting to deposit or fetch data in the locations within the string 
designated by the subroutine.  

A good way to get the subroutine into the string variable is to read it from 
a disk file as shown in the first example below.  The machine language code 
must be in memory image format and must be position independent since it may 
be loaded anywhere.  Naturally, care should be taken in using this statement 
as improper use can cause system failure. The DOS utility called EXE2BIN may 
be of use in preparing the subroutine file.  

Programming note: Since PILOT string variables are always terminated by a 
null character, ( a zero byte) you may need to avoid placing zero bytes 
within the data passed to and from the machine language subroutine. A zero 
byte would look like the end of the string when using subscripting to access 
bytes within the string.  

EXAMPLE: Using the EXEC program of the Advanced Feature Library to execute 
another DOS program as a subroutine. 

       DX: EXEC$(600)
       FX: EXEC.BIN
       FI: 0,EXEC$
       C: EXEC$(9,80) = "TURBO XYZ"
       V: EXEC$
 
See also:  sample program SAMPLE4.PIL

WAIT - program delay

       W: expression
       WH:expression

WAIT causes a program delay for expression tenths of a second.  The delay is 
prematurely ended if the student pushes a key.  

EXAMPLE 1: WAIT 10 seconds or until a key is hit 

       W:100

WAIT AND HOLD

Normally, if the WAIT is ended by the student pushing a key, the value of the 
keypress is discarded and the program continues. Appending the H, or HOLD, 
modifier to the WAIT changes this.  If the student pushes a key, the WH: 
statement is ended, but the keypress is not discarded. Instead, it is left in 
the type-ahead buffer so that it can be read by a subsequent ACCEPT 
statement, or KEY function.  

EXAMPLE 2: WAIT HOLD. This example shows a typical use for WAIT. At a pause 
point within the program the student is instructed to push a key to go on. 
The WH:30000 would wait essentially forever. When the student pushes a key, 
the WH: ends and the  KEY function is used to see what key was pushed.  If it 
is the ESC key, then the SYSX routine is called in much the same manner as it 
would be called automatically by an ACCEPT.  

       T:Push any key to go on.
       WH:30000
       U(KEY(0)=27):SYSX

Programming note: The TS:Dn command may be used to force a delay which can 
not be interupted by the keyboard. 
  
EXECUTE INDIRECT - execute a string


       XI: expression
       X: expression

EXECUTE INDIRECT allows you to construct a PILOT statement within a string, 
then execute the statement. This very unique language feature turns out to be 
an extremely powerful programming tool.  

EXECUTE INDIRECT evaluates the expression to its string value.  Then the 
string value is executed as if it were a PILOT statement.  The string may 
contain any valid statement up to length 255. If the string is too long only 
the first 255 characters are used.  

Programming note: The "I" of "XI" may be omitted; it is allowed for 
compatibility with other versions of PILOT.  

EXAMPLE 1: Random problem selection. Assume that there are 10 problems, each 
with a label PROB0, PROB1, etc. This statement could be used to select one at 
random.  

       X: "J:PROB" !! RND(10)


EXAMPLE 2: Save a frequently used graphic sequence in a string for repeated 
use.  

       C: BOX$="G:*4(F50;R90;F100;R90)"
       ...
       X: BOX$


EXAMPLE 3: Save viewport parameters in strings to simplify switching among 
several viewports.  

       C:QUES$ = "TS:V0,18,3,17;B1;F3"
       C:ANSW$ = "TS:V20,38,5,9;B2;F4"
       . . .
       X: QUES$
       T: What is the Magna Carta?
       X: ANSW$
       A:


EXAMPLE 4: A desk calculator constructed via the EXECUTE INDIRECT statement.  

       *DESK
       TH:Enter an expression here: 
       A:
       X: "C: X = " !! %B
       T:The result is #X
       J:DESK


See Also: SAMPLE1.PIL